feat: ship shared plugin hooks (hooks/hooks.json) + docs

Merge gate cleared — release N shipped as stable v0.8.0 on 2026-08-03, and it is Latest.

This PR was held because a plugin installed from the default branch would have called agent-hook, a command the then-published v0.7.2 did not have. Verified against the shipped artifact rather than the source tree, since that is what users actually download: basecamp_0.8.0_darwin_arm64.tar.gz reports basecamp version 0.8.0 and exposes exactly the three subcommands hooks/hooks.json invokes (session-start, pre-commit-snapshot, post-commit). The full flow was then exercised end to end against that binary: snapshot → commit BC-4455 → nudge emitted with the reference and short hash.

Rebased onto main (was 45 commits behind); bin/ci exit 0.

What

One hooks/hooks.json at the plugin root serves both agents (both read the same location, same matcher semantics, same hookSpecificOutput wire):

• SessionStart (startup|resume|clear|compact) → basecamp agent-hook session-start — auth status as model context, with a spinner label.
• PreToolUse / PostToolUse (Bash) → pre-commit-snapshot / post-commit — the paired HEAD-snapshot commit nudge. No statusMessage on these: they run on every Bash call and stay visually silent.
• PostToolUseFailure (Bash) → post-commit — closes the old accepted asymmetry: on Claude, git commit && git push with a failed push still nudges (the commit is proven from repo state, not the tool result). Codex ignores unknown event names inside hooks (verified: HookEventsToml lacks deny_unknown_fields), so this key is inert there; Codex's own PostToolUse fires regardless of exit status. No other top-level keys — Codex hard-errors on unknown top-level keys in hooks.json.

Commands are plain basecamp agent-hook <sub> strings — valid under all four hook shells (sh -lc, cmd.exe /C, Git Bash, PowerShell); no wrapper, no commandWindows, no per-agent split.

Docs/setup restoration (reverses the Phase 1 deferrals from cb139726):

• README + install.md: "hooks" back in the plugin feature lists; Codex sections regain "review and trust the plugin hooks with /hooks" (Codex lists untrusted hooks but silently does not run them until trusted). Claude needs no trust step — install consent covers it.
• runCodexSetup: re-adds the muted "Review and trust the plugin hooks with /hooks." next-step line; the wizard test flips from proving /hooks absent to proving it present.
• AGENTS.md tree: hooks/ entry back (agent-neutral wording).
• .codex-plugin/plugin.json longDescription: restores the connect-commits clause.

TestHooksFileCommandsInvokeBasecamp (dormant since #534) activates automatically now that hooks/hooks.json exists.

Compatibility floor

Hooks require CLI ≥ release N. Users of either agent with an older CLI may see non-blocking hook errors after their plugin payload refreshes (Codex: on marketplace upgrade; Claude: at the release N+1 manifest version bump, which can auto-update the plugin while the user still runs CLI < N). Remediation: basecamp upgrade. Codex additionally keeps new hooks inert until /hooks trust.

Rollout

• Codex users get the payload on codex plugin marketplace upgrade 37signals (or basecamp setup codex), then must trust via /hooks.
• Claude users get it at release N+1's manifest version bump (plugin auto-update).
• Production verification happens after N+1: session-start context, the nudge matrix, doctor at matching versions. Staging passes before merge don't substitute.

Staging verification (pre-merge, candidate payload + dev-build CLI)

Both agents were verified against this branch's SHA (4f28a810) with production plugins isolated first (Codex: throwaway CODEX_HOME + staging marketplace 37signals-staging pinned to the SHA, install positively attributed; Claude: production basecamp@37signals disabled, candidate loaded via --plugin-dir), then production state restored.

• Codex 0.144.6 (codex exec --dangerously-bypass-hook-trust, dev-build basecamp on PATH): SessionStart context injected verbatim ("Basecamp is active and OAuth is ready…"); scratch repo commit with BC-123 → nudge delivered as developer context with the short hash; failed commit (nothing staged) → NONE. /hooks trust flow itself not exercisable non-interactively — the bypass flag exercises the same execution path post-trust.
• Claude Code 2.1.216: PostToolUse nudge on todo-456 commit quoted back by the model; PostToolUseFailure on commit-then-failed-push quoted the BC-777 nudge verbatim — the asymmetry this event closes, verified live. SessionStart verified at the transcript level: hook executed, stdout parsed, context attached as hook_additional_context (models don't always attribute it when asked, but injection is proven).
• TestHooksFileCommandsInvokeBasecamp now runs (not skipped) and passes; full bin/ci green on this branch.

Summary by cubic

Ships shared plugin hooks for Codex and Claude via hooks/hooks.json to add session-start status and Git commit-to-todo nudges. Widens hook timeouts and updates docs to require a CLI with agent-hook, plus trust-first guidance in Codex.

• New Features

  • Single hooks/hooks.json for both agents: SessionStart injects auth status; Bash PreToolUse/PostToolUse drive commit nudges; PostToolUseFailure (Claude) also nudges after a failed push; timeouts set to 5s/10s/12s.
  • Hooks run basecamp agent-hook <sub> across shells and stay silent on Bash. Codex ignores unknown hook event names and rejects unknown top-level keys.
  • Docs/setup: README/install document the agent-hook CLI requirement; Codex setup now says “trust hooks with /hooks” before “start a new thread”; .codex-plugin/plugin.json mentions commit linking; AGENTS.md lists hooks/.

• Migration

  • Requires basecamp CLI with agent-hook (release N+). If hook errors appear after install/refresh, run basecamp upgrade, start a new session, and check with basecamp agent-hook --help (“unknown command” means the CLI is too old).
  • Codex: trust hooks with /hooks, then start a new thread. Claude needs no trust step.

^{Written for commit 7e605dd. Summary will update on new commits.}